Aminet 6

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / util / rexx / config_server.lzh / doc / config-editor.doc next >

Wrap

Text File | 1995-02-13 | 16.6 KB | 406 lines

config-editor provides you with a means to edit the config-server database. See the "legal.doc" file for copyright, disclaimer, and license. I was going to make a GUI version of this, but the only ARexx-usable GUI systems are in commercial/demo form, buggy, difficult, and/or feature-poor. None was really suitable. The closest was EDMI, but Henry Neufeld, the author of EDMI, moved to MS-WINDOWS I'm told. EDMI has some slight display bugs and is also very clumsy and slow. (I know about these problems because I use Henry's (or Rick Huebner's?) EDMI scripts for my Proteus-based BBS.) To install: Make sure bin/set_con and bin/set_raw are on your command search path. Put config-editor.rexx somewhere you want (maybe in REXX:, or maybe in your command search path). You may wish to set the Script bit for config-editor and/or remove the .rexx filename suffix to make execution easier. (I keep the .rexx suffix in the distribution so that you can _see_ that it's an ARexx program, rather than having to peer at its insides to determine that fact.) Make sure you have config-server set up and running. First trial use: Type: rx bin/config-editor.rexx ...you should see a list of applications appear: ::Applications:: config-server Indra's-Net IndraSMTPd IndraSMTPc test ::Quit:: ...use the up/down arrow keys to move around. You can use the <Del> (press the key marked `Del') or <D> (press the key marked `D') keys to delete any of these "applications" from config-server's database. Try it. Move down to, say, IndraSMTPd, and type <Del> or <D>. You should see the IndraSMTPd entry disappear, and your "active spot" shouldn't move. Yes? But, wait! We didn't want to do that (not yet; you might want to do it permamently sometime). Well, don't worry. We didn't _save_ the change back to disk, we just modified the in-memory copy of the database. Type <R> to Reload the database. After a brief pause, the database should be reload, the screen should clear, and the list should be redrawn (with the IndraSMTPd restored to it's position). There are three other commands available at this menu: <Q> to Quit (does the same thing as selecting the ::Quit:: entry). <S> to Save the database. This saves the config-server database to ENV: _and_ to ENVARC:. <Right arrow> (->) to "move into" the currently selected Application. (<Return> does the same thing as <Right arrow>, by the way.) (Oh, I forgot to mention. <D>, <Q>, <R>, and <S>, are NOT case-sensitive; you can type them as upper or lower-case. Okay, let's move on. Move the cursor to the "config-server" Application entry and then press <Return> or <Right arrow>. You should see this list appear: ::Tags for config-server:: COMMENT ::Quit:: This is a list of items that are defined for config-server. Config-server doesn't have any configuration entries save a (set of) COMMENT line(s). Later, you may explore the other entries for other applications, but we'll stick with config-server, for now. A note about the ::Quit:: entries: All menus have ::Quit::. This is NOT a program-quit, but rather a quit-from-this-menu. (I may make both options available at some point, but currently you must back out through the menus.) All ::Quit:: menu items act as if you typed the <Q> key. It only Quits the program when you are at the top-level menu. A note about the arrow keys: I tried to emulate the UNIX `lynx' program's use of the arrow keys (and of <Return>). This means that <Left arrow> means "back out a level" at all menus, save the outer-most level (where you can't back out any further). (To be more like `lynx', I may have `Q' always quit the program...) Last note: Delete works at this level, too. You could delete all COMMENT entries for an application at this level by selecting the COMMENT entry and typing <Del> or <D>. DON'T DO IT. Not yet, at least. (^& We have some other stuff to do first, and if you deleted something at this level, you would have to return to the top level to Reload. Commands available: <Up arrow>/<Down arrow> Select a tag-type. <D>/<Del> Delete the current tag-type for this application's config. <Left arrow>/<Q> Move out of this application's config. <Right arrow> Move into the "details" of the current tag-type for this application's config. Okay, there's not much to do here. Move the cursor to the COMMENT line, and use <Return> or <Right arrow> to go into it. There may be a significant delay, now. (There is a delay of almost a second, on my 25mHz 68030.) The delay is caused because there are quite a few COMMENT entries. When the delay is over, you should see: ::Tag subs for config-server:COMMENT:: TEXT: Foo, this is a comment: <=- ! TEXT: TEXT: Config-server is a capable program for almost TEXT: any application to use. It provides the app- TEXT: application with flexible options in TEXT: configuration processing. Simple applications TEXT: can just do this: TEXT: TEXT: OPTIONS RESULTS TEXT: ADDRESS 'config-server' TEXT: 'getattr val' APP':'TAG_FOR_VAR TEXT: PARSE RESULT 'TEXT:'VAR_TO_USE TEXT: TEXT: config-server is part of the Indra's Net project TEXT: that I'm working on. However, the name is TEXT: deliberately not suggestive of this fact. The TEXT: reason for this is that config-server has TEXT: applicability outside of Indra's Net, and so TEXT: it is styled more along the lines of a general TEXT: Amiga system tool. ...hm. The "TEXT:" prefix on each line is the "encoding" for that line. All of these lines shown are encoded as "TEXT" type lines. There are other types available, but for now we won't worry about them. (See some of the other entries for some of the other applications -- and read config-server's documentation.) Okay. Move the cursor to the second line (the first "blank" line). Yes, the one under "Foo, this is a comment: <=- !". Now, type the key. You should see: ::New application:encoding:tag:value:: Data: app: config-server enc: TEXT tag: COMMENT num: --- val: App: ...the cursor should be stopped after the "App: " line at the bottom. Hit <Return> and the "app:config-server" line should be printed in inverted colors, and the "App: " prompt at the bottom should become "Enc: ". Hit <Return> again for Enc: and Tag:, fields, and you should see each converted, above, into inverse video. Finally, hit <Return> on the "Val: " prompt. There will be another delay, then the screen should refresh with all of those "TEXT: ...." comment lines. (Note: Ignore the `num: ---' line for now. It will eventually be used, but not just yet. It "can't" be used due to a current limitation of config-server. Fixing it isn't impossible, but it isn't a priority, either.) If you are observant, you will notice a new line at the bottom, though. A blank line. Curious! Okay, let's try this. Move the cursor up to the top line (the one that starts "Foo, ..." and type again. You should see: ::New application:encoding:tag:value:: Data: app: config-server enc: TEXT tag: COMMENT num: --- val: Foo, this is a comment: <=- ! App: Hit <Return> four times, again, and you should see each of the App:, Enc:, Tag, and Val: prompts/highlights just as before -- and then return to the "menu" for comments. If you look at the bottom, you will see that the top-most "Foo, ..." line has been replicated to the bottom. (NOTE: At this point, if you are using a bordered Shell window on a non-interlaced, non-overscanned, NTSC display, with a standard-height font, you may have scrolling problems. Sorry; I use interlaced all of the time, and probably won't address scrolling issues until I get more than about 50 entries for a single tag. (^& Fortunately, COMMENTS are the only fields likely to exceed more than a couple of entries, and for reading COMMENTS, you can just as well load the config-server.config file into any text editor and read it that way. So, don't worry too much. If you DO have scrolling problems, delete a couple of lines in the middle, or something.) Well, that's all very interesting, huh? But what if we want to enter a new config entry? Simple. After pressing , each of those prompts (App:, Enc:, Tag:, and Val:) represents a point where you can enter your own text! The meanings of the lines are best explained by the config-server documentation...but in brief: App: Application name. By default, the current application is used. Enc: Encoding type. By default, the encoding type of the currently selected tag-sub is used. The default is "TEXT", if you are on the ::Quit:: when you type the (which is unavoidable if you've deleted all of the tag-sub's). Tag: The type of config-entry you are creating. Default will be the same type you are looking at when you type the . Val: The value for the new config-entry. Default will be the same value as the type you are looking at when you type the , or a blank if you are on the ::Quit::. In case you hadn't guessed: The app:, enc:, tag:, num: (ignored for now), and val: fields above the input-prompt are initially filled in with the current defaults, and as you enter each piece, the piece is overwritten on top of the prior entry. Okay, let's create a new config-server:COMMENT entry: Type , and you get the familiar "entry form" menu. App: Since we want to make a new config-server entry, and since we are making our new entry from a point under the config-server's application entry, our default is "config-server". We can just hit <Return>, as before. Enc: We can make it something other than TEXT, but I suggest for now (and probably comment's should _always_ be TEXT...). I'll make mine a TEXT entry, which in this case is the default, so I'll hit <Return> again. Tag: We said we wanted a config-server:COMMENT entry, so we'll once again hit <Return> and accept the default (isn't that neat? *grin*). Val: Here you can write anything you want. Due to lack of deep intelligence on config-editor's part, I _suggest_ you keep the new line short enough to fit on your screen, with the Encoding prefix. Mine will be: This is a new comment. My new line, when I'm returned to the tag-sub menu, looks like this: TEXT:This is a new comment. ...you may notice that it doesn't have that stylish space after the "TEXT:" and before the "real text" of the entry. This is perfectly okay. The COMMENT entries that I prepared for you have the space because I put the space in there -- to make the comments more readable. However, config-editor and config-server don't need the extra space, so if you don't add one, it won't matter. GENERALLY, I would not advise adding spaces for non-COMMENT fields. COMMENT's are ignored by applications, so their content and format isn't important to anyone but humans. On the other hand, non-COMMENT fields are read and interpreted by applications. Because of this, spaces may be significant in non-COMMENT fields (whether they are depends on the encoding type of the field, as well; TEXT fields have their spaces preserved for the application to deal with; FILE type encodings with spaces will mean that the file searched for must have the same spacing in its filename). Okay, maybe now you want to delete the three COMMENT's we've added to the config-server database. Move down to the first line we inserted (the last "blank" line, if you've followed the above instructions correctly). Now, hit the <Del> (or <D>) key 3 times. Each of the three new lines we added should disappear (with pauses as config-editor regenerates it's list from the database after each deletion). Poof, we should be back to where we started. (Alternatively, we could just go to the top-level menu and type <R> to Reload.) The commands available at this menu level: <Up arrow>/<Down arrow> Select a tag-sub to work with. <Right arrow>/<Return> Go into an option (doesn't work with anything but the ::Quit:: option; you can't "go into" a tag-sub). <Left arrow>/<Q> Go back out a menu level. <Del>/<D> Delete the current tag-sub. Insert a new tag-sub (actually _appends_ at the moment; insertion will be supported in time). Play around. Read the other COMMENT fields for the other application entries. Try creating whole new tag-types and/or application entries. Delete some of the ones you create. If you've read all of the COMMENT fields, you may wish to delete them, and/or most/all of the other application entries. This will speed loading/reloading/saving. NOTE: Keep at least one tag-sub for at least one tag for at least one app. (See Bugs for related info.) I.e., don't delete EVERYTHING. Ideas (feedback appreciated): One interesting concept is that of an "umbrella" pseudo-application. Not a real application, but one that a suite of related applicatoins can turn to to get common configuration info. E.g., my Indra's Net programs will probably all look at an Indra's Net or Indra's-Net type of entry for "broad" configuration info, then look to more application-specific info to override/supplement the general info. Another important concept is that there can be multiple occurances (tag-subs) of each tag. In some cases, such as a SIGNATURE tag for a message system, you will probably only want ONE entry (the last entry); for other cases (e.g., a list of name-servers to consult) you might be interested in all of them being used. In some cases you might care whether, say, an "umbrella application" entry is compounded with, or overridden by, a more specific application's entry, for a given application. These questions of how to deal with multiplicity are probably best answered on an application-by-application, tag-by-tag basis. Users should be aware of this concept, and programmers should give it thought. Perhaps some convention for "continuation" entries should be given, so that the _user_ can mark certain tag-subs as being intended for compounding with other tag-subs. Some standard tags, with standard interpretations are probably a good idea. E.g., a LOG field that behaves in generally the same way for all aplications. (These thoughts really belong in the config-server.doc file...(^&) Bugs: ** Insert (adding a field) always inserts at end. (This is only a problem with the config-server, and should eventually be fixed.) ** Reloading/saving is only supported at the outermost menu-level; inserting only at the innermost. You CAN, however, delete individual 'tag-subs', whole groups of like-named tags in a single app, or whole applications from config-server. Just use the <Del> or <D> key (your choice) at the appropriate level. ** No on-screen reminders of what keys are valid (or for what actions). ** Insertion can only be done at the tag-sub level. If you have no applications, with tags, you can't get to the tag-sub level, so you can't create new entries if you have carelessly wiped out the old ones. (This is fixable by Reloading (if you haven't Saved your deletions), reverting to the original env/config-server.config file and inserting from there, or by manually writing the config-server.config file with a text editor.) ** Scrolling due to too-many-entries, and wrapping due to too-long-entries, is not addressed by config-editor. It should be.